package com.fortify.awb;

import com.fortify.awb.bugtracker.BugtrackerFields;

/**
 * This interface is provided for implementing custom bug trackers for use within Fortify's
 * graphical user environment tools.
 * <br>
 * The bug tracker workflow is as follows:
 * <ol>
 * 	<li> User selects an issue and chooses to file a bug.
 * 	<li> If this is the first bug being filed, they are presented with a list of all registered
 * 	bug tracker implementations, and are asked to select one.
 * 	<li> The Fortify tool fills in the default bug fields from method {@link #getDefaultFields()}.
 *  <li> The Fortify tool fills in the "Summary", "Description", and "Comments" values from the
 *  selected issue.
 *  <li> The Fortify tool displays the "File Bug" dialog.
 *  <li> The user reviews, and optionally changes any existing fields in the "File bug" dialog.
 *  The user cannot create new fields, delete fields, or change field names.
 *  <li> The user clicks the "Submit" button.
 *  <li> The Fortify tool invokes the {@link #submit(BugtrackerFields)} method with the fields
 *  from the dialog.
 *  <li> If the {@link #submit(BugtrackerFields)} method returns true, the "File Bug" dialog
 *  reports success and returns control to the user interface.
 *  <li> If the {@link #submit(BugtrackerFields)} method returns false, an error dialog is displayed.
 * </ol>
 * To use this interface, first create a Java class that implements this interface. For example,
 * <blockquote><pre>
 *   public class MyThing implements com.fortify.awb.BugtrackerPlugin {
 *   }
 * </pre></blockquote>
 * Then, implement the {@link #toString()} method to provide the name that will be displayed in the
 * list of registered implementations.  For example,
 * <blockquote><pre>
 *   public String toString() {
 *     return "My Thing";
 *   }
 * </pre></blockquote>
 * Next, consider which pieces of information are required by your bug tracking software. All
 * information that is provided to your bug tracking software is handled in the {@link com.fortify.awb.bugtracker.BugtrackerField}
 * and {@link com.fortify.awb.bugtracker.BugtrackerFields} classes.  A {@link com.fortify.awb.bugtracker.BugtrackerField} can contain an immutable list of possible values.
 * <br><br>
 * Some of the information will be end user-definable, and some other information may not be
 * visible to the end user.
 * <br><br>
 * The Fortify graphical tool will add three keys, "Summary", "Description", and "Comments", to the
 * data.  The user will have an opportunity to overwrite these values.
 * <br><br>
 * If you want the user to be able to view and edit any other values, return those values in the
 * {@link #getDefaultFields()} method.  For example, if the bug tracker software requires a value
 * for "color", and you want to present the user with a default value "blue", AND you want the 
 * user to be able to review and modify this default "blue", implement the following:
 * <blockquote><pre>
 *   public BugtrackerFields getDefaultFields() {
 *     BugtrackerFields fields = new BugtrackerFields();
 *     fields.addFieldWithDefaultValue("Priority", "P2");
 *     return fields;
 *   }
 * </pre></blockquote>
 * Finally, implement the {@link #submit(BugtrackerFields)} method with logic appropriate to your bug tracking system.
 */
public interface BugtrackerPlugin {
	
	/**
	 * When the user clicks on the "File bug" control in the Fortify user interface
	 * for the first time, a list of the available bug tracker plugins is presented.
	 * <br>
	 * This method returns the name of the Bugtracker plugin as it will display to the 
	 * user in that list.
	 * 
	 * @return The user selectable name of the bug tracker implementation.
	 * */
	String toString();
	
	/**
	 * When the user submits a bug using the Fortify "File bug" control, the "File bug..."
	 * dialog appears, with a table of fields and their optional pre-filled default values.
	 * The user has the ability to overwrite any value, but not to edit, add or remove any keys.
	 * If possible values are included on a field, they will only be able to select one of those
	 * possible values from a drop down control.  If there are no possible values, they will be
	 * presented with a free-form text editor instead.
	 * <br>
	 * This method returns the fields, along with any associated default values that display 
	 * to the user.
	 * <br>
	 * (The Fortify tool will automatically add the "Summary", "Description", and "Comments" 
	 * fields to the form; those do not need to be returned here.) 
	 * 
	 * @return The bugtracker fields and any associated default values offered to the user.
	 * */
	BugtrackerFields getDefaultFields();
	
	/**
	 * When the user clicks the "Submit" control on the "File bug..." dialog, the Fortify tool
	 * sends all of the fields defined in the options parameter to the bug tracker software interface.
	 * <br>
	 * This method returns true if the submittal succeeds.  If this method returns false, an 
	 * error dialog is presented to the user interface.
	 * 
	 * @param options Key value pairs representing the information to be sent to the bug tracking software.
	 * The "Summary", "Description", and "Comments" keys will always be set by the Fortify tool.  All values can 
	 * be overwritten by the user before submittal.
	 * @return true if the request succeeds; and false if an error dialog should display to the user interface.
	 * */
	boolean submit(BugtrackerFields options);
	
	/**
	 * This method returns the formatted string that's presented to the user in the Description text box
	 * in the File Bug... dialog.
	 */
	String renderDescription(String abstractText, String rawIssueXML);
}
